Hello Quarto

What is Quarto?

Quarto® is an open-source scientific and technical publishing system built on Pandoc

Quarto integrates what has been learned over the last 10-years from RMarkdown into one system for creating and publishing reproducible documents.

The R Markdown ecosystem

Quarto: Next generation R Markdown

Quarto highlights

Consistent implementation of attractive and handy features across outputs

More accessible defaults as well as better support for accessibility

Guardrails, particularly helpful for new learners: YAML completion, code option completion

Support for other languages like Python, Julia, and more

Some highlights of these improvements include

–> consistent implementation of attractive and handy features across all outputs, like tabsets, code-folding, and syntax highlighting,

–> more accessible defaults as well as better support for creating accessible documents,

–> guardrails that are particularly helpful for new learners, like YAML completion and informative syntax errors,

–> and perhaps most excitingly for those who are not coming from the R ecosystem, Quarto offers support for other languages like Python, Julia, and more via the Jupyter engine for executable code chunks. And it’s designed to be expandable to more engines and languages, even those that might not exist today.

[pause] So by now I’m assuming many of you have already started playing with Quarto, or you’re waiting for me to do that. So, let’s dive in and see what all the Quarto fuss is about!

Quarto makes moving between formats straightforward

Document

lesson-1.qmd

title: "Lesson 1"
format: html

Presentation

lesson-1.qmd

title: "Lesson 1"
format: revealjs

Website

_quarto.yml

project:
  type: website

website: 
  navbar: 
    left:
      - lesson-1.qmd

What did spark my interest was how how straightforward it is with Quarto to move between output formats.

As an educator, two things are of utmost importance to me about the tools I use to create my materials: reproducibility and ease of transition between output formats, like documents to slides to websites to books.

Over the last year of using Quarto for pretty much everything, I’ve felt like I’ve finally found the tool that lets me go from one output type to the other with minimal, if any, futzing around with my source code beyond the yaml. For example, here are common things I produce

–> a lesson in document form
–> the same content in presentation form
–> the same content on a page in a website,

and you can see that all that needed to change going between these formats is a few lines in the yaml. Nothing in the content part of my document. No slide breaks to remove, no citation style to change, no headings to re-level. This ease of transition has freed up time to focus my time on content, and that, folks, is the dream!

Let’s get started!

Open RStudio
Click on “File”
Select “New File”
Select “Quarto Document”
- Fill in the title and author
- Select HTML for the format option
Click “Create”!

A Quarto Document

---
title: "ggplot2 demo"
author: "Norah Jones"
date: "May 22nd, 2021"
format: 
  html:
    code-fold: true
---

## Air Quality

@fig-airquality further explores the impact of temperature 
  on ozone level.

```{r}
#| label: fig-airquality
#| fig-cap: Temperature and ozone level.
#| warning: false

library(ggplot2)
ggplot(airquality, 
       mapping = aes(x = Temp, y = Ozone)
       ) + 

  geom_point() + 
  geom_smooth(method = "loess"
)
```

Anatomy of a Quarto document

The YAML metadata or header is:

processed in many stages of the rendering process and can influence the final document in many different ways. It is placed at the very beginning of the document and is read by each of Pandoc, Quarto and knitr. Along the way, the information that it contains can affect the code, content, and the rendering process.

Required Inputs

What editor should be the default for working in the document?

---
editor: visual
---

What format should the document render in?

---
format: html
---

Code

```{r}
#| output-location: column-fragment
#| label: species-means
#| tbl-cap: Mean body mass (g) of penguins on Palmer Archipelego
#| warning: false

library(palmerpenguins)

penguins %>%
  drop_na(body_mass_g) %>% 
  group_by(species) %>% 
  summarize(mean_weight = mean(body_mass_g)
            )
```

# A tibble: 3 × 2
  species   mean_weight
  <fct>           <dbl>
1 Adelie          3701.
2 Chinstrap       3733.
3 Gentoo          5076.

{r} – notates what language the code is written in

#| – defines code chunk options

Text

Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax. Markdown is a plain text format that is designed to be easy to write, and, even more importantly, easy to read

# Heading 1
This is a sentence with some **bold text**, some *italic text* and an [image](image.png).

Text Formatting

Markdown Syntax	Output
`italics and bold`	italics and bold
`superscript^2^ / subscript~2~`	superscript² / subscript₂
`~~strikethrough~~`	~~strikethrough~~
`verbatim code`	`verbatim code`

Headings

Markdown Syntax	Output
`# Header 1`	Header 1
`## Header 2`	Header 2
`### Header 3`	Header 3
`#### Header 4`	Header 4
`##### Header 5`	Header 5
`###### Header 6`	Header 6

Additional YAML Options

---
format: 
  html:
    code-fold: true
---

Notice!

html: is now on a new line
this line is below format: and indented
the HTML formatting options are on their own line
these lines are below html: and indented

Your turn!

The exhaustive list of YAML options that can be used for HTML documents can be found here: https://quarto.org/docs/reference/formats/html.

Using this resource add the following to your document:

code folding
is self-contained
center alignment of all figures
an execution option which suppresses messages output from R

Afterward, add at least one additional YAML option of your choosing!